# Guideline tạo task cho AI Flow Kit

## 1. Nguyên tắc

- Con người cung cấp những gì chỉ con người có: màn hình, nguyên văn khách nói, mục đích, bối cảnh.
- **Con người tách task và khoanh phạm vi:** yêu cầu lớn thành danh sách UC/task, mỗi task chỉ về chức năng/màn hình nào. AI chỉ gợi ý nếu cần.
- **Kit phân tích chi tiết và viết spec trong từng task:** Fact / Assumption / Gap, business rule, Q&A, UC Spec, System Requirement. Con người trả lời Q&A và duyệt.
- Chưa biết thì ghi `Chưa rõ`, **không bỏ trống**. Kit biến `Chưa rõ` thành câu hỏi (Gap); ô trống khiến kit tự đoán.

## 2. Tiêu chí ticket cha (yêu cầu của khách)

| # | Tiêu chí | Đạt khi | Không đạt |
|---|---|---|---|
| 1 | Một mục tiêu | Mục tiêu nghiệm thu được bằng 1 câu | "Làm chức năng group" |
| 2 | Chỉ rõ vị trí thay đổi | Có ít nhất 1 trong: màn hình (tên + URL + screenshot lưu trong repo), module/file, functionId | "Bỏ dialog" (màn hình nào?) |
| 3 | Hiện trạng → Mong muốn | Có thao tác hiện tại → kết quả mong muốn | Chỉ có mong muốn |
| 4 | Lý do | Nêu vấn đề nghiệp vụ, hoặc ghi `Chưa rõ` | Bỏ trống |
| 5 | Nguồn gốc | Nguyên văn của khách (không sửa), dán vào ticket + link | Chỉ có bản diễn giải của member |
| 6 | Phạm vi vừa | Tối đa 1 functionId / 3 màn hình; có mục Ngoài phạm vi | "Giống hệ thống X" mà không chỉ ra màn hình nào của X |

Không đạt tiêu chí 6: không tạo bộ subtask Create Spec/Coding ngay. PM/BrSE tự tách thành nhiều ticket cha nhỏ, mỗi ticket đạt đủ 6 tiêu chí. Nếu thiếu thông tin để tách, chạy bước Điều tra nghiệp vụ trước (kit `ingest-data` / `investigation`); kết quả của kit chỉ để tham khảo.

Lý do con người tách task:

- Muốn AI tách một yêu cầu rộng thì AI phải đọc toàn bộ yêu cầu trong một session. Đây chính là nguyên nhân tràn context, phân tích nông và tốn token.
- Tách task cần thông tin AI không có: ưu tiên của khách, estimate, hợp đồng, kế hoạch sprint, người được assign.
- Người biết dự án tách được trong 15–30 phút và chính xác hơn.

## 3. Subtask theo bước kit

Subtask không chép lại yêu cầu. Mỗi subtask chỉ ghi: link ticket cha + input + output mong đợi.

| Subtask | taskType kit | Input | Output |
|---|---|---|---|
| Điều tra nghiệp vụ | `investigation` / `ingest-data` | Ticket cha + câu trả lời của khách | Q&A log + thông tin để PM/BrSE tách UC/task |
| Create Spec | `create-spec` | Ticket cha + Q&A đã Confirmed | UC Spec (PM sign-off) |
| Create System Requirement | `create-system-requirement` | UC Spec đã sign-off + source code | System Requirement (trace 1-1 với UC Spec) |
| Coding | `feature` / `bug-fix` | System Requirement khớp version UC Spec | Code + PR |
| Create testcase | `create-testcase` | UC Spec + System Requirement | Test case |
| Execute test | `execute` | Test case + bản build | Test report |

Ghi chú:

- Create Spec và Create System Requirement là 2 subtask riêng. Create System Requirement chỉ bắt đầu khi UC Spec đã được PM sign-off.
- Create System Requirement chạy 1 lần cho mỗi functionId và mỗi version UC Spec, không chạy theo từng ticket coding. UC Spec lên version mới thì tạo lại subtask này.
- Coding cần System Requirement khớp version UC Spec hiện tại. Nếu thiếu, kit cảnh báo ở Gate 1 và đề nghị chạy `create-system-requirement` trước.
- Nếu Điều tra nghiệp vụ ra nhiều Use Case, lặp lại bộ subtask Create Spec / Create System Requirement / Coding / Create testcase / Execute test cho từng UC. Bộ subtask cố định một lần chỉ dùng khi ticket cha có 1 UC.

## 4. Mẫu

### Mẫu ticket cha

Nội dung dưới đây là ví dụ minh hoạ. Thay bằng thông tin thật của dự án.

```markdown
## Mục tiêu
Admin tạo được account cho người dùng mới ngay trên màn hình admin, không phải nhờ dev tạo qua DB.

## Vị trí thay đổi
- Màn hình: Quản lý user (admin) — /admin/users — screenshot: AK-Docs/<đường dẫn>/admin-users.png
- Code: <module user/admin, nếu biết>
- functionId: <nếu có>

## Hiện trạng → Mong muốn
- Hiện tại: muốn có account mới → khách gửi yêu cầu → dev insert DB tay
- Mong muốn: admin bấm "Tạo account" → nhập thông tin → hệ thống tạo account và gửi mail cho user

## Lý do / mục đích của khách
Giảm thời gian chờ cấp account, khách tự chủ động.
Chưa rõ: cần phân quyền ai được tạo account không — cần hỏi khách.

## Nguồn gốc
> 管理画面からアカウント発行できるようにしてください。
- Link: WONDER-1135, <email/meeting log ngày ...>

## Ngoài phạm vi
- Import account hàng loạt từ CSV
- Sửa luồng đăng nhập hiện tại

## (Khuyến nghị) Tiêu chí nghiệm thu
- [ ] Admin tạo được account với email chưa tồn tại
- [ ] Email trùng → báo lỗi, không tạo
- [ ] User nhận được mail kích hoạt

## (Khuyến nghị) Hệ thống tham chiếu / Ràng buộc
- <link + màn hình cụ thể, nếu yêu cầu nói "giống X">
```

### Mẫu subtask

Mỗi subtask ứng với 1 Use Case / 1 functionId. Phần trong `< >` thay bằng thông tin thật. Subtask không chép lại nội dung ticket cha; chỉ ghi phạm vi, input, output của bước đó.

#### Điều tra nghiệp vụ (`ingest-data` / `investigation`)

```markdown
## Ticket cha
<link ticket cha> (dán link vào description để kit fetch được)

## Loại task
ingest-data (đưa trao đổi của khách vào AK-Docs)
hoặc investigation (khảo sát source code / hệ thống tham chiếu)

## Phạm vi điều tra
- Chức năng: <tên chức năng của ticket cha>
- Màn hình cần xem (tối đa 3–5 mỗi lần chạy):
  - <tên màn hình> — <URL/route> — screenshot: <đường dẫn file trong repo>
- Hệ thống tham chiếu (nếu có): <URL> — tài khoản: <nơi lấy tài khoản> — màn hình: <liệt kê>
- Ngoài phạm vi: <phần KHÔNG điều tra lần này>

## Input
- Yêu cầu gốc: <ticket ID cha / link Backlog, Jira>
- Trao đổi với khách: <link Backlog/Jira>, hoặc nội dung dán trực tiếp (SharePoint, email, chat)
- Câu hỏi đã biết cần hỏi khách: <liệt kê, hoặc "Chưa có">

## Output mong đợi
- Entry trong `AK-Docs/01.QnA/` (QnA-Log / Meetings-Log / Confirmations-Log)
- Thông tin để PM/BrSE tách UC / functionId: màn hình, luồng, vai trò người dùng tìm thấy
- Danh sách câu hỏi cần khách trả lời

## Điều kiện hoàn thành
- [ ] PM/BrSE đã chốt danh sách UC / task con (mỗi UC thành 1 bộ subtask)
- [ ] Câu hỏi Blocking đã gửi khách
```

#### Create Spec (`create-spec`)

```markdown
## Ticket cha
<link ticket cha> (dán link vào description để kit fetch được)

## Loại task
create-spec

## functionId
<functionId> (bắt buộc, kit dừng ở Gate 1 nếu thiếu)

## Mode
- [ ] CREATE: functionId chưa có UC Spec
- [ ] UPDATE: đã có `UC-Spec_v<N>.md`, task này sửa thành v<N+1>
Lý do UPDATE (nếu có): <thay đổi gì so với bản cũ>

## Phạm vi Use Case
- Use Case: <tên UC, ví dụ "Admin tạo account">
- Vai trò người dùng: <ví dụ: Admin>
- Màn hình (tối đa 3):
  - <tên màn hình> — <URL/route> — screenshot: <đường dẫn file trong repo>
- Ngoài phạm vi: <UC/màn hình KHÔNG làm trong task này>

## Input
- Yêu cầu gốc: <ticket ID cha> (kit fetch được nếu là link Backlog/Jira)
- Q&A đã Confirmed: <đường dẫn QnA-Log / Confirmations-Log, hoặc ticket Điều tra nghiệp vụ>
- Thiết kế: <link Figma, nếu có> / <đường dẫn file thiết kế trong repo>
- Tài liệu khác: <đường dẫn file trong repo; tài liệu trên Drive/SharePoint phải tải về trước>
- Câu hỏi còn Open: <liệt kê, hoặc "Không">

## Output mong đợi
- `AK-Docs/02.BA-Specs/01.Analysis/<functionId>/Analysis_v<n>.md`
- `AK-Docs/02.BA-Specs/02.QnA/<functionId>/QnA-Log_v<m>.md` (gửi khách nếu còn câu Open)
- `AK-Docs/02.BA-Specs/03.UI-Prototypes/<functionId>/UI-Prototype_v1.html`
- `AK-Docs/02.BA-Specs/04.UC-Specs/<functionId>/UC-Spec_v<N>.md`

## Điều kiện hoàn thành
- [ ] Mọi câu hỏi Blocking đã Confirmed
- [ ] UI Prototype đã được BA/khách xác nhận
- [ ] UC Spec đã được PM sign-off (điều kiện để bắt đầu Create System Requirement)
```

#### Create System Requirement (`create-system-requirement`)

```markdown
## Ticket cha
<link ticket cha> (dán link vào description để kit fetch được)

## Loại task
create-system-requirement

## functionId
<functionId>

## UC Spec nguồn
`AK-Docs/02.BA-Specs/04.UC-Specs/<functionId>/UC-Spec_v<N>.md` (đã PM sign-off)

## Mode
- [ ] CREATE: functionId chưa có System Requirement
- [ ] RESYNC: đã có System Requirement nhưng trace tới UC Spec version cũ (v<N-1>)

## Source code liên quan
- Module: <tên module / package>
- File chính (nếu biết): <đường dẫn>
- Ngoài phạm vi: <module KHÔNG cần đọc>

## Output mong đợi
- `AK-Docs/02.BA-Specs/00.Requirements/<functionId>/System-Requirement_v<N>.md`
  gồm Functional/Non-Functional Requirement, Validation Rule, Exception/Error Handling, Acceptance Test
- Trace 1-1 với UC Spec v<N>; không thêm nội dung UC Spec không có

## Điều kiện hoàn thành
- [ ] Mọi Gap đã Confirmed
- [ ] Dev và Tester đã review
```

#### Coding — tính năng (`feature`)

```markdown
## Ticket cha
<link ticket cha> (dán link vào description để kit fetch được)

## Loại task
feature

## functionId
<functionId>

## Tài liệu nguồn
- UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/<functionId>/UC-Spec_v<N>.md`
- System Requirement: `AK-Docs/02.BA-Specs/00.Requirements/<functionId>/System-Requirement_v<N>.md`
- Thiết kế: <link Figma> / <đường dẫn file trong repo>

## Phạm vi code
- Luồng làm trong task này: <ví dụ: tạo account; KHÔNG gồm sửa/khoá account>
- Module / file dự kiến: <đường dẫn, nếu biết>
- Ngoài phạm vi: <luồng, module KHÔNG sửa>
- Ràng buộc: <không đổi schema DB / giữ API cũ tương thích / ...>

## Output mong đợi
- Requirement doc: `AK-Docs/04.Coding/01.Requirements/<functionId>/<ticket ID>.md`
- Plan: `AK-Docs/04.Coding/02.Plans/<functionId>/<ticket ID>.md`
- Code + unit test (TDD), Review doc, Pull Request

## Điều kiện hoàn thành
- [ ] Test pass
- [ ] Acceptance Test trong System Requirement đều đạt
- [ ] PR đã được review
```

#### Coding — sửa bug (`bug-fix`)

```markdown
## Ticket cha
<link ticket yêu cầu / bug report của khách> (dán link vào description để kit fetch được)

## Loại task
bug-fix

## functionId
<functionId, nếu biết>

## Vị trí thay đổi
- Màn hình: <tên màn hình> — <URL/route> — screenshot: <đường dẫn file trong repo>
- Code nghi ngờ: <module / file, nếu biết>

## Mô tả lỗi
- Môi trường: <dev / staging / production> — version/branch: <...>
- Bước tái hiện:
  1. <...>
  2. <...>
- Kết quả thực tế: <...>
- Kết quả mong đợi: <...> (căn cứ: <UC Spec / System Requirement mục ..., hoặc "Chưa rõ">)
- Tần suất: <luôn luôn / thỉnh thoảng / 1 lần>
- Log lỗi: <chỉ dòng lỗi quyết định và stack trace ngắn>

## Nguồn gốc
> <nguyên văn báo lỗi của khách>
- Link: <ticket / email>

## Ngoài phạm vi
- <phần KHÔNG sửa, ví dụ: refactor module liên quan>

## Điều kiện hoàn thành
- [ ] Có test tái hiện lỗi, fail trước khi sửa và pass sau khi sửa
- [ ] Không ảnh hưởng chức năng khác (kit chạy impact-analysis ở Gate 4)
```

#### Create testcase (`create-testcase`)

```markdown
## Ticket cha
<link ticket cha> (dán link vào description để kit fetch được)

## Loại task
create-testcase

## functionId
<functionId>

## Tài liệu nguồn (bắt buộc cả hai)
- UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/<functionId>/UC-Spec_v<N>.md`
- System Requirement: `AK-Docs/02.BA-Specs/00.Requirements/<functionId>/System-Requirement_v<N>.md`

## Phạm vi test
- Use Case: <tên UC>
- Loại test: <functional / UI / validation / phân quyền / ...>
- Ngoài phạm vi: <ví dụ: performance, các UC khác>
- Môi trường / dữ liệu test: <tài khoản test, dữ liệu mẫu, nơi lấy>

## Output mong đợi
- `AK-Docs/03.Testing/01.Testcases/<functionId>/<functionId>_TestCase.md` (khoảng 30–50 test case)
- `AK-Docs/03.Testing/01.Testcases/<functionId>/<functionId>_Dev_Checklist.md`
- QnA và Review result trong cùng thư mục

## Điều kiện hoàn thành
- [ ] Mọi câu hỏi cho BA/khách đã Confirmed
- [ ] Test case đã qua review
```

#### Execute test (`execute`)

```markdown
## Ticket cha
<link ticket cha> (dán link vào description để kit fetch được)

## Loại task
execute

## functionId
<functionId>

## Bộ test case
- File: `AK-Docs/03.Testing/01.Testcases/<functionId>/<functionId>_TestCase.md`
- Phạm vi chạy: <toàn bộ / nhóm TC: TC_ID ...>

## Môi trường
- BASE_URL: <URL môi trường test>
- Build / branch: <version đã deploy>
- Tài khoản test: <nơi lấy tài khoản; không ghi mật khẩu vào ticket>
- Điều kiện trước: <dữ liệu cần có sẵn>
- MCP Playwright đã cấu hình: <Có / Chưa>

## Output mong đợi
- Report: `AK-Docs/03.Testing/02.Reports/<repo>/<feature>/run-<N>/testreport.md`
- Evidence: `AK-Docs/03.Testing/04.Evidence/<repo>/<feature>/run-<N>/` (không commit)
- Bug phát sinh: ghi nhận và tạo ticket bug-fix riêng

## Điều kiện hoàn thành
- [ ] Đã chạy đủ phạm vi TC
- [ ] TC fail đã có ticket bug hoặc lý do chấp nhận
```

## 5. Scope task để không vượt context của AI session

Giới hạn scope theo lượng AI phải đọc trong một session, không theo độ khó của task. Mỗi task là đơn vị nghiệm thu nhỏ nhất của bước đó: 1 Use Case, 1 màn hình chính, 1 bộ test case.

### Context bị chiếm bởi gì

- Instruction và skill của kit: cố định, chiếm một phần đáng kể trước khi task bắt đầu.
- Input: ticket, spec, Q&A log, screenshot.
- File code AI đọc: 1 file khoảng 300 dòng tốn khoảng 3–5k token.
- Output của tool: log test, log build, kết quả search.
- Hội thoại Q&A qua các gate.

Chất lượng phân tích giảm trước khi context đầy. Khi bị auto-compact, AI mất chi tiết. Hướng tới việc mỗi session chỉ dùng tối đa khoảng một nửa context.

### Giới hạn scope theo loại subtask

Các con số dưới đây là mức khởi điểm. Cần đo lại trên dự án thật.

| Subtask | Scope 1 task | Dấu hiệu quá rộng | Cách tách |
|---|---|---|---|
| Điều tra nghiệp vụ | 1 chức năng (1 ticket cha). Hệ thống tham chiếu: tối đa 3–5 màn hình mỗi lần chạy | Phải mở cả module của hệ thống tham chiếu | Mỗi nhóm màn hình một lần điều tra; output là danh sách UC |
| Create Spec | 1 Use Case / 1 functionId, tối đa 3 màn hình | UC Spec có nhiều UC độc lập; nhiều vai trò người dùng | Mỗi UC một subtask Create Spec |
| Create System Requirement | 1 functionId / 1 version UC Spec | AI phải đọc source code của nhiều module; UC Spec chứa nhiều UC | Tách theo UC Spec. Không gộp FR/VR để giảm số item |
| Coding | 1 UC. Đọc/sửa tối đa khoảng 10–15 file, diff tối đa khoảng 500 dòng, ước lượng tối đa 8h | Chạm nhiều module; cần đọc lại nhiều lần; kit báo XL ở Gate 1 | Tách theo luồng người dùng, ví dụ: tạo → sửa → xoá. Không tách theo FE/BE |
| Create testcase | 1 UC, khoảng 30–50 test case | Test case cho nhiều UC trong một lần chạy | Mỗi UC một subtask |
| Execute test | 1 bộ test case của 1 UC | Log test quá dài | Chạy theo nhóm; chỉ đưa phần log lỗi vào |

Không gộp nhiều item để giảm số lượng. Nếu thiếu token budget, giảm scope. Không làm requirement/test case thô hơn.

### Quy tắc khi chạy session

1. **1 gate = 1 session.** Kết thúc gate thì artifact đã nằm trong file (AK-Docs). Mở session mới rồi chạy `ak task resume <ticket-id>` để AI đọc lại từ file, không mang theo hội thoại cũ.
2. **Truyền bằng link/đường dẫn, không dán nội dung.** Spec, log, tài liệu dài thì đưa đường dẫn để AI đọc phần cần thiết. Chỉ dùng loại link kit đọc được (xem §6) hoặc đường dẫn file trong repo.
3. **Không dán nguyên log.** Chỉ dán dòng lỗi quyết định và stack trace ngắn.
4. **Mục Ngoài phạm vi bắt buộc với task lớn.** Mục này ngăn AI đọc lan sang phần không liên quan.
5. **Session bị compact, hoặc AI hỏi lại điều đã chốt, là dấu hiệu task quá rộng.** Dừng lại và tách task. Không cố chạy tiếp.

## 6. Lưu ý khi chạy kit

- `ak use --file` lấy **tên file** làm tiêu đề và chỉ đọc **3000 ký tự đầu**. Đưa 6 trường bắt buộc lên đầu; tài liệu dài để dạng link hoặc đường dẫn file.

### Link nào kit tự đọc được

| Nguồn | Kit xử lý thế nào |
|---|---|
| Backlog / Jira: ticket, comment | `ak use` tự fetch link trong mô tả ticket, tối đa 5 link |
| Backlog: Document, Wiki | Không tự fetch từ mô tả ticket. Chỉ đọc khi chạy `ak fetch-links "<url>"` (luồng `ingest-data` dùng lệnh này) |
| SharePoint | Không đọc được. Kit nhận ra link nhưng chưa có connector, trả về `sharepoint-not-configured` |
| Google Drive / Google Docs / link khác | Không đọc được. Kit bỏ qua link |
| File đính kèm trên Backlog/Jira (ảnh, Excel, PDF) | Không đọc được. Kit chỉ lấy nội dung text và comment của ticket |

Với nguồn kit không đọc được:

- Tài liệu trên Drive/SharePoint: tải file về, lưu vào repo (ví dụ trong `AK-Docs/`), ghi đường dẫn file vào task. Hoặc dán phần nội dung liên quan vào task.
- Comment của khách trên SharePoint: copy nguyên văn vào mục Nguồn gốc. Vẫn giữ link để trace.
- Screenshot: lưu file ảnh vào repo và ghi đường dẫn. Ảnh chỉ đính kèm trên Backlog thì AI không thấy.
- Vẫn ghi link gốc trong task để con người trace lại, nhưng không coi link đó là input của AI.

### Kit chỉ fetch link ở 1 tầng

Khi chạy `ak use <ticket con>`, kit đọc ticket con và các link trong description của ticket con. Kit không fetch tiếp các link nằm bên trong ticket vừa fetch.

| Nội dung | Kit có đọc không |
|---|---|
| Ticket con: description + comment | Có |
| Link ticket cha trong description của ticket con | Có. Chỉ lấy title và 2000 ký tự đầu của description ticket cha, không lấy comment |
| Link Backlog nằm trong description của ticket cha | Không |
| Link ticket cha chỉ nằm trong comment của ticket con | Không. Kit chỉ quét link trong description |
| Quan hệ cha-con chỉ set bằng trường "Parent" của Backlog, không dán link | Không |

Giới hạn khác: kit tự fetch tối đa 5 link trong description của ticket con.

Cách xử lý:

1. Dán link ticket cha vào **description** của ticket con, không chỉ set trường "Parent".
2. Link Backlog nào AI cần đọc thì dán thẳng vào description của ticket con (tối đa 5 link). Không dựa vào link nằm trong ticket cha.
3. Hoặc liệt kê ticket trong lệnh: `ak use <ticket con> <ticket cha> <ticket khác>`. Ticket đầu là task chính; các ticket sau được nạp làm ngữ cảnh bổ sung (mỗi ticket lấy title + 2000 ký tự description).
4. Link còn thiếu khi đang chạy: yêu cầu AI chạy `ak fetch-links "<url>"`.
5. Trong ticket cha, đặt nội dung quan trọng (mục tiêu, vị trí thay đổi, hiện trạng → mong muốn) lên đầu description, vì kit chỉ đọc 2000 ký tự đầu.
- `ak use` mặc định là mode `fast`, bỏ qua Q&A. Ticket có `Chưa rõ` thì chạy `--full`.

## 7. Kiểm tra nhanh trước khi tạo task

- [ ] Mục tiêu viết được trong 1 câu, không có chữ "và"
- [ ] Chỉ rõ vị trí thay đổi: màn hình, file/module hoặc functionId
- [ ] Có hiện trạng → mong muốn
- [ ] Có lý do, hoặc ghi `Chưa rõ`
- [ ] Có nguyên văn của khách + link
- [ ] Liệt kê được các màn hình/file chính, không quá 3 màn hình hoặc khoảng 15 file
- [ ] Không cần đọc toàn bộ hệ thống tham chiếu
- [ ] Người làm tay ước lượng không quá 8h
